home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 071-080 / amok73 / ums / doc / ums.doc < prev    next >
Text File  |  1993-11-04  |  46KB  |  1,249 lines
  1. TABLE OF CONTENTS
  2.  
  3. ums.library/--background--
  4. ums.library/AllocUMSPattern
  5. ums.library/CannotExport
  6. ums.library/DeleteUMSMsg
  7. ums.library/ExportedMsg
  8. ums.library/FreeUMSConfig
  9. ums.library/FreeUMSMsg
  10. ums.library/FreeUMSPattern
  11. ums.library/LogUMS
  12. ums.library/MatchUMSPattern
  13. ums.library/ReadUMSConfig
  14. ums.library/ReadUMSMsg
  15. ums.library/UMSErrNum
  16. ums.library/UMSErrTxt
  17. ums.library/UMSLogin
  18. ums.library/UMSLogout
  19. ums.library/UMSRLogin
  20. ums.library/UMSSearch
  21. ums.library/UMSSelect
  22. ums.library/WriteUMSConfig
  23. ums.library/WriteUMSMsg
  24. ums.library/--background--                         ums.library/--background--
  25.  
  26.        $VER: 9.5 (15-Jul-92)
  27.  
  28.        COPYRIGHT
  29.  
  30.          This document is (C) 1992 by Martin Horneffer.
  31.  
  32.          It may freely be copied and distributed, as long as the text is
  33.        unchanged and this copyright notice is left intact.
  34.  
  35.        GENERAL
  36.  
  37.          UMS stands for "Universal Message System".
  38.  
  39.          This  means  that  UMS  allows  to  treat  and read all kinds of
  40.        messages  ('e-mail'  and 'news') as universally and efficiently as
  41.        possible.
  42.  
  43.          The  user  should  not need to care about what network a message
  44.        comes  from  or goes to/through and what format is used, he or she
  45.        should be able to concentrate totally on the messages' contents.
  46.  
  47.          In order to achieve this goal, UMS does two things:
  48.  
  49.          1) define an universal format for messages where messages in all
  50.        formats  and  from  all  networks can be stored in without loss of
  51.        information and nevertheless being randomly interchangeable.
  52.  
  53.          2) implement  a central, network-independent database-mamagement
  54.        that  allows to store and read/retrieve messages in the UMS format
  55.        as efficiently as possible.
  56.  
  57.          For  the message format, please read the separate documentation.
  58.  
  59.          The  implementation  of  the  Message  Base Processor ('MBP') is
  60.        based  on  the server/client- concept.  Clients address the server
  61.        to  get  or  put  messages.   The  server  manages the storage and
  62.        retrieval   of   messages  and  controls  the  different  client's
  63.        access-rights  to the system.  The common interface between client
  64.        and server is a set of functions described in this document.
  65.  
  66.          Clients are
  67.          -  simple  USERS  that  read  and write messages (using programs
  68.        called 'newsreaders'),
  69.          -  a  special  kind  of  user, the 'SYSOP', which has additional
  70.        rights and tools to administer the system,
  71.          -  IMPORTERS,  that get messages form other systems and put them
  72.        into the local system after converting them to the UMS format, and
  73.          -  EXPORTERS,  that  look for all NEW messages in the system and
  74.        send them to other systems after converting them into the specific
  75.        format.
  76.  
  77.          The  MBP  controls  which user may read what message and, in the
  78.        same  way, which exporter needs to export or forward what message.
  79.        It  cares  about whether a message can or cannot be correctly sent
  80.        to its destination.
  81.          The  MBP  also  performs  dupe-checking  and  reply-chaining  on
  82.        Message-IDs.
  83.  
  84.  
  85.        HISTORY
  86.  
  87.           8. 7.92:
  88.          documentation of tags WAutoBounce, WHdrFill, WTxtFill.
  89.  
  90.           2. 7.92:
  91.          added documentation for tag RIDStyle and several config tags.
  92.  
  93.           4. 7.92: 9.1
  94.          first version of an autodoc for ums.library V9
  95.  
  96.          12. 7.92:
  97.          added some general information
  98.  
  99.  
  100.        TAGS
  101.  
  102.          UMS uses some bit-masking in tag values to indicate some special
  103.        types of tag data:
  104.  
  105.          if  bit 13 is set (tag & 0x2000), the tag data is a STRPTR, i.e.
  106.        a pointer to a null-terminated string.
  107.  
  108.          if  bit  14 is set (tag & 0x4000), the tag is considered a 'var-
  109.        parameter'  (e.g.  LONG *).  I.e.  the tag.data entry must contain
  110.        a  pointer  to  the  real  data,  which will be set/changed by the
  111.        called function.
  112.  
  113.          if both bits 13 and 14 are set ((tag & 0x6000)==0x6000), the tag
  114.        is a pointer to a string pointer which will be set/changed (STRPTR
  115.        *).
  116.  
  117.          if none of these bits is set, the data in most cases is a simple
  118.        integer parameter (e.g.  LONG or LONGBITS).
  119.  
  120. ums.library/AllocUMSPattern                       ums.library/AllocUMSPattern
  121.  
  122.    NAME
  123.        AllocUMSPattern -- Precompile an AmigaDOS style pattern.
  124.  
  125.    SYNOPSIS
  126.        pHandle = AllocUMSPattern( pattern, case )
  127.          D0                         D2      D3
  128.  
  129.        LONG AllocUMSPattern( STRPTR, BOOL );
  130.  
  131.    FUNCTION
  132.          Precompile a pattern for later use with MatchUMSPattern(),
  133.        UMSSelect() or UMSSearch().
  134.  
  135.    INPUTS
  136.        pattern - AmigaDOS compatible pattern.
  137.        case    - whether the pattern-matching should be
  138.                  case-sensitive or not.
  139.  
  140.    RESULT
  141.        pHandle - A handle only to be used by MatchUMSPattern(),
  142.                  FreeUMSPattern() and other functions in ums.library.
  143.                  NULL if compiling was not successful.
  144.  
  145.    NOTES
  146.          You MUST deallocate every compiled pattern-handle with
  147.        FreeUMSPattern()!
  148.          The  UMS  pattern-matching  routines  may  or  may  not use Dos'
  149.        pattern-matching  routines internally.  They are however different
  150.        in  that  they  allocate  all  the  needed memory for you and they
  151.        remember whether you wanted a pattern to be case-sensitive or not.
  152.          The  idea  of UMS' private pattern-matching routines is that you
  153.        precompile  a  pattern  only  once and then use it as often as you
  154.        need it with any ums-function that supports an appropriate tag.
  155.  
  156.    SEE ALSO
  157.        FreeUMSPattern(), MatchUMSPattern()
  158.  
  159. ums.library/CannotExport                             ums.library/CannotExport
  160.  
  161.    NAME
  162.        CannotExport -- Mark a message as not being exportable.
  163.  
  164.    SYNOPSIS
  165.        CannotExport( login, msgNum, error )
  166.                       D2      D3     D4
  167.  
  168.        VOID CannotExport( LONG, LONG, STRPTR );
  169.  
  170.    FUNCTION
  171.          Tell  the  MBP  that  you cannot export this message, due to any
  172.        reason.   The MBP will then look if other exporters still could be
  173.        able to export the message or do some error processing otherwise.
  174.          It may use the supplied error-string therein.  This error-string
  175.        should  be  a  short  description  why  the  message  could not be
  176.        exported.  By convention it should not be longer than 80 bytes.
  177.  
  178.    INPUTS
  179.        msgNum - Number of the message.
  180.        error  - Short string (<80 chars).
  181.  
  182.    NOTES
  183.          This function may only be called by exporters.
  184.          See also ExportedMsg().
  185.  
  186.    BUGS
  187.          The  MBP currently does not write a bounce mail to the author of
  188.        the mail, but sets a special global bit instead, which would allow
  189.        a 'bounce daemon' to automatically write bounce mails.
  190.  
  191.    SEE ALSO
  192.        ExportedMsg()
  193.  
  194. ums.library/DeleteUMSMsg                             ums.library/DeleteUMSMsg
  195.  
  196.    NAME
  197.        DeleteUMSMsg -- Delete a message.
  198.  
  199.    SYNOPSIS
  200.        success = DeleteUMSMsg( login, msgNum )
  201.          D0                     D2      D3
  202.  
  203.        BOOL DeleteUMSMsg( LONG, LONG);
  204.  
  205.    FUNCTION
  206.          This  functions deletes a message, specified by number, from the
  207.        UMS MB.
  208.          It does not necessarily free space on the hd, but it removes the
  209.        message  logically from the MB so that no other user can access it
  210.        anymore and it won't affect the dupe-check for new messages.
  211.          The  MBP  may need reorganization to physically remove logically
  212.        deleted messages.
  213.  
  214.    INPUTS
  215.        msgNum  -  Number  of  the  message to be deleted.  As returned by
  216.                   UMSSearch() or WriteUMSMsg().
  217.  
  218.    RESULT
  219.        success  -  Inidcates  whether the message was actually deleted or
  220.                    not.   It  will  be  not  deleted  if  you  don't have
  221.                    write-access  to  this  message or the message doesn't
  222.                    exist.
  223.  
  224.    NOTES
  225.          The  number of a message is valid only as long as you are logged
  226.        in.  After UMSLogout() messages numbers may change!
  227.          So  you  always  have  to  use the real Message-ID to remember a
  228.        message persistently.
  229.  
  230. ums.library/ExportedMsg                               ums.library/ExportedMsg
  231.  
  232.    NAME
  233.        ExportedMsg -- Mark a message as being successfully exported.
  234.  
  235.    SYNOPSIS
  236.        ExportedMsg( login, msgNum )
  237.                      D2      D3
  238.  
  239.        VOID ExportedMsg( LONG, LONG );
  240.  
  241.    FUNCTION
  242.          Tells  the  MBP  that  a message has been successfully exported.
  243.        The  MBP  uses  this  information  to prevent other exporters from
  244.        wrongly  exporting  this message a second time or writing a bounce
  245.        message.
  246.  
  247.          Every  exporter that exports a message from the local UMS system
  248.        to  any  other system or network MUST call either ExportedMsg() or
  249.        CannotExport()  for  each message it has processed.  This is valid
  250.        for  private  messages as well as for public messages (news).  The
  251.        MBP will decide what has to be done in any of these cases.
  252.  
  253.    INPUTS
  254.        msgNum - Number of the exported message.
  255.  
  256.    NOTES
  257.          This function may only be called by exporters.
  258.  
  259.    SEE ALSO
  260.        CannotExport()
  261.  
  262. ums.library/FreeUMSConfig                           ums.library/FreeUMSConfig
  263.  
  264.    NAME
  265.        FreeUMSConfig -- Free a string returned by ReadUMSConfig().
  266.  
  267.    SYNOPSIS
  268.        FreeUMSConfig( login, string)
  269.                        D2      D3
  270.  
  271.        FreeUMSConfig( LONG, STRPTR);
  272.  
  273.    FUNCTION
  274.          Frees  the  buffer  for  a  string  allocated  and  returned  by
  275.        ReadUMSConfig().   After 'FreeUMSConfig(string)', 'string' will be
  276.        invalid.
  277.  
  278.    INPUTS
  279.        string - string returned by ReadUMSConfig().
  280.  
  281.    SEE ALSO
  282.        ReadUMSConfig()
  283.  
  284. ums.library/FreeUMSMsg                                 ums.library/FreeUMSMsg
  285.  
  286.    NAME
  287.        FreeUMSMsg -- Free buffers associated with a certain message.
  288.  
  289.    SYNOPSIS
  290.        FreeUMSMsg( login, msgNum )
  291.                     D2      D3
  292.  
  293.        FreeUMSMsg( LONG, LONG );
  294.  
  295.    FUNCTION
  296.          Frees  all  the  buffers  associated  with  a  certain  message.
  297.        ReadUMSMsg() allocates the buffers, this function frees them.
  298.  
  299.    INPUTS
  300.        msgNum - number of the message previously read with ReadUMSMsg().
  301.  
  302.    NOTES
  303.          With  FreeUMSMsg()  all  STRPTRs obtained with ReadUMSMsg() that
  304.        are  concerned  with this certain message become invalid.  You can
  305.        have  multiple  ReadUMSMsg()  on  the  same  message  but only one
  306.        FreeUMSMsg().
  307.  
  308.    SEE ALSO
  309.        ReadUMSMsg()
  310.  
  311. ums.library/FreeUMSPattern                         ums.library/FreeUMSPattern
  312.  
  313.    NAME
  314.        FreeUMSPattern -- Frees a precompiled pattern.
  315.  
  316.    SYNOPSIS
  317.        FreeUMSPattern( pHandle )
  318.                          D2
  319.  
  320.        VOID FreeUMSPattern( LONG );
  321.  
  322.    FUNCTION
  323.          Free a pattern-handle formerly created by AllocUMSPattern().
  324.  
  325.    INPUTS
  326.        pHandle - Pattern-handle returned by AllocUMSPattern().
  327.  
  328.    SEE ALSO
  329.        AllocUMSPattern()
  330.  
  331. ums.library/LogUMS                                         ums.library/LogUMS
  332.  
  333.    NAME
  334.        LogUMS -- Write an entry to the global UMS logfile.
  335.  
  336.    SYNOPSIS
  337.        LogUMS( login, level, format, args )
  338.                  D2    D4      D5     D6
  339.  
  340.        LogUMS( LONG, LONG, STRPTR, LONG * );
  341.  
  342.        LogUms( login, level, format, ... )
  343.  
  344.        LogUms( LONG, LONG, STRPTR, ... )
  345.  
  346.    FUNCTION
  347.          Write  a  short  message  to the UMS logfile, doing printf-style
  348.        formatting on supplied parameters.
  349.          Rather  than creating all its own logfile, an application should
  350.        use this function to report its actions and/or errors.  This makes
  351.        it  easier for the user to get an overview on what is happening in
  352.        his system - he only has to look in ONE logfile.
  353.          LogUMS()  uses  a  'level'-parameter to decide whether a message
  354.        should  actually  be  written  to  the logfile or be ignored.  The
  355.        lower  this  number, the more important is the message.  Choose it
  356.        as follows:
  357.  
  358.          1-4:  an ERROR.  1=very fatal error, 4=recoverable error.
  359.          5-7:  general information or report.
  360.          8-9:  information that is not useful for normal operation, but
  361.                used for debugging purposes.
  362.  
  363.          Of  course  messages with higher level-values should appear more
  364.        frequently than those with low level-values.
  365.  
  366.    INPUTS
  367.          level - Number between 1 and 9.
  368.         format - Printf-style format-string.  See RawDoFmt() for more
  369.                  information on formatting.
  370.           args - Arguments for the format-string.
  371.  
  372.    SEE ALSO
  373.        RawDoFmt()
  374.  
  375. ums.library/MatchUMSPattern                       ums.library/MatchUMSPattern
  376.  
  377.    NAME
  378.        MatchUMSPattern -- Check whether a pattern matches a string.
  379.  
  380.    SYNOPSIS
  381.        match = MatchUMSPattern( pHandle, string )
  382.         D0                        D2       D3
  383.  
  384.        BOOL MatchUMSPattern( LONG, STRPTR );
  385.  
  386.    FUNCTION
  387.          Checks whether a string matches to a precompiled pattern.
  388.  
  389.    INPUTS
  390.        pHandle - Pattern-handle as returned by AllocUMSPattern().
  391.        string  - String to match against the given pattern.
  392.  
  393.    RESULT
  394.        match - TRUE if the string matches the pattern, FALSE otherwise.
  395.  
  396.    SEE ALSO
  397.        AllocUMSPattern()
  398.  
  399. ums.library/ReadUMSConfig                           ums.library/ReadUMSConfig
  400.  
  401.    NAME
  402.        ReadUMSConfig -- Read something from the global configuration.
  403.  
  404.    SYNOPSIS
  405.        string = ReadUMSConfig( login, tags )
  406.          D0                     D2     D3
  407.  
  408.        STRPTR ReadUMSConfig( LONG, struct TagIten * );
  409.  
  410.        string = ReadUMSConfigTags( login, tag1, ... )
  411.  
  412.        STRPTR ReadUMSConfigTags( LONG, ULONG, ... );
  413.  
  414.    FUNCTION
  415.          Read a config object from the global UMS configuration.
  416.  
  417.          Whenever  possible,  applications  should  use  the  global  UMS
  418.        configuration and this function instead of extra config-files.
  419.  
  420.          A  'config-string'  is a null-terminated string identified by an
  421.        unique   name.    Similar   to  shell-  and  environment-variables
  422.        config-strings  can  be global (same for all users) or local (only
  423.        visible to a certain user).
  424.  
  425.          Other   config-objects  are  'users'  (with  aliases  and  local
  426.        strings), 'akas' and 'netgroups'.
  427.  
  428.          In   order   not   to   mix  up  config-strings  of  different
  429.        applications,  their  names  should have the id of the application
  430.        and  a  dot  prepended.   E.g.   "fido.outbound",  "fido.inbound",
  431.        "uucp.uuspool", "magicmail.publicScreenName", etc.
  432.          The  MBP  enforces  this  convention  by  not  accepting  config
  433.        elements without a dot (".").
  434.  
  435.          Names for config elements are case-insensitive.
  436.  
  437.          This function buffers the returned string until it is freed with
  438.        FreeUMSConfig() or (UMSLogout()).
  439.  
  440.    INPUTS
  441.          The following tags are allowed:
  442.  
  443.          CfgGlobalOnly         : (none)
  444.                read just global config-elements, ignore local ones.
  445.  
  446.          CfgUser               : STRPTR
  447.                read  config  elements  local  to  another user.  You must
  448.        specify  the  name  of  the  other  user  here.   This contradicts
  449.        CfgGlobalOnly!
  450.  
  451.          CfgMatchPattern       : LONG  (by AllocUMSPattern())
  452.                (Not yet implemented in V9.)
  453.                Only  search  for  config  elements  that  match  a  given
  454.        pattern.   You  must  use  a  pattern-handle  here  that  has been
  455.        returned   by  AllocUMSPattern()  not  not  yet  been  freed  with
  456.        FreeUMSPattern().
  457.  
  458.  
  459.          The  following  tags are mutually exclusive.  Use exactly one of
  460.        them.
  461.  
  462.          CfgStringName         : STRPTR
  463.                read a config-string with given name.
  464.  
  465.          CfgUserName           : STRPTR
  466.                get the 'realname' for a user with a given alias.
  467.  
  468.          CfgSameNetgroup       : STRPTR
  469.                (Not yet implemented in V9)
  470.                get the next groupname for the same netgroup.
  471.                Any  number  of groupnames  may be configured as identical
  472.        'netgroups'.  Using this tag you can get another name for the same
  473.        'netgroup'  as the given groupname.  Using this tag repeatedly you
  474.        can  cycle trough all names for the same group.  Because these are
  475.        organized  in  a  circular  structure you must do a string-compare
  476.        with  the  original  string to detect when you are finished.  This
  477.        returns  NULL  only  when  the  given  string  doesn't  indicate a
  478.        netgroup at all.
  479.  
  480.          CfgNextAka            : STRPTR
  481.          CfgNextNetgroup       : STRPTR
  482.          CfgNextUser           : STRPTR
  483.          CfgNextAlias          : STRPTR
  484.          CfgNextString         : STRPTR
  485.                (Not yet implemented in V9)
  486.                These  tags  allow  you to scan all existing configuration
  487.        objects.   On  first invocation you set the tag's data to NULL and
  488.        get the name of the first element.  Then you always set it to what
  489.        has been returned on the last call.  When NULL is returned, you're
  490.        finished.
  491.                You   may  use  CfgUser  together  with  CfgNextAlias  and
  492.        CfgNextString.  CfgGlobalOnly is redundant as it's the default.
  493.  
  494.    RESULT
  495.        string - a pointer to the desired config element, or NULL.
  496.  
  497.    BUGS
  498.              Some  of  the tags are not implemented yet.  Tell the author
  499.        (Martin Horneffer) when you need them!
  500.  
  501.    SEE ALSO
  502.        FreeUMSConfig(), WriteUMSConfig()
  503.  
  504. ums.library/ReadUMSMsg                                 ums.library/ReadUMSMsg
  505.  
  506.    NAME
  507.        ReadUMSMsg -- Read (parts of) a message.
  508.  
  509.    SYNOPSIS
  510.        success = ReadUMSMsg( login, tags )
  511.          D0                   D2     D3
  512.  
  513.        BOOL ReadUMSMsg( LONG, struct TagItem * );
  514.  
  515.        success = ReadUMSMsgTags( login, tag1, ... )
  516.  
  517.        BOOL ReadUMSMsgTags( LONG, ULONG, ... );
  518.  
  519.    FUNCTION
  520.          Read a message or any parts of it.
  521.  
  522.    INPUTS
  523.          The following tags are allowed:
  524.  
  525.          RMsgNum               : LONG
  526.                specify which msg to read. This tag MUST be used!
  527.  
  528.          RHeaderLength         : LONG *
  529.                you have to pass a pointer to a LONG here.  This LONG will
  530.        be  set  to  the length of the message-header in bytes.  I.e.  the
  531.        length  of all text-fields considered to belong to the 'header' of
  532.        a message.
  533.  
  534.          RTextLength           : LONG *
  535.                like  RHeaderLength,  but  the length of the message-text.
  536.        These are all other fields.
  537.  
  538.          RMsgDate              : LONG *
  539.                the  date the message has been written to the message-base
  540.        (also  referred  to  as  the  'receive-date').  In AmigaDOS Format
  541.        (seconds since 1.1.1978).
  542.  
  543.          RChainUp,
  544.          RChainDn,
  545.          RChainLt,
  546.          RChainRt              : LONG *
  547.                reply-chaining.   Since  a  message  can only refer to one
  548.        other  (older)  message,  but have multiple other (newer) messages
  549.        referring  to  it, a tree is built out of this 'comment-chaining'.
  550.        ChainUp  points to the referred message.  ChainDn points to one of
  551.        the messages that comment on the current one.  ChainLt and ChainRt
  552.        point to other messages which share the same ChainUp.
  553.                The  LONG  you  supply a pointer to in the tag's data will
  554.        either  be  set  to  zero  (when there is no such chain) or to the
  555.        number of a message.
  556.  
  557.          RGlobalFlags          : LONGBITS *
  558.                global  flags  for  this message.  In the MB every message
  559.        has  exactly one set of global flags.  See <ums.h> for the meaning
  560.        of these flags.
  561.  
  562.          RUserFlags            : LONGBITS *
  563.                user-flags for this message.  Every user of the MB has one
  564.        set  of user-flags for each message.  See <ums.h> for the fixed or
  565.        suggested meanings of these flags.
  566.  
  567.          RLoginFlags           : LONGBITS *
  568.                login-flags  for  this message.  Every login has a private
  569.        set  of  flags  for  each  message.   In  contrast  to  global  or
  570.        user-flags,  login-flags  are NOT saved and vanish on UMSLogout().
  571.        They are set to zero on UMSLogin().
  572.  
  573.          RHardLink,
  574.          RSoftLink             : LONG *
  575.                a  pointer  to another link in the circular linked list of
  576.        linked  messages.   Zero  if  a  real  message  (no  link).  Since
  577.        message-links can be either hard or soft, but not both at the same
  578.        time, only one of these can be non-zero.
  579.  
  580.          RDateStyle            : LONG
  581.                use  this  tag and set its data to 1 if you want to get an
  582.        old-style  'receive-date'.   Don't use this tag or set its data to
  583.        zero otherwise.
  584.  
  585.          RMsgText, ..
  586.          RMsgText + 127        : STRPTR *
  587.                tell  UMS  that  you want to read the specified text-field
  588.        and  supply a place for a pointer to it.  This will be set to NULL
  589.        if  the  field  doesn't  exist  or  you're not allowed to read it.
  590.  
  591.          RTextFields           : UMSMsgTextFields
  592.                if  you  supply  a pointer to an array of 128 STRPTR here,
  593.        it  will  be  set  to  the read text-fields.  Useful for reading a
  594.        whole  message  without  having to specify a tag for each possible
  595.        text-field.
  596.  
  597.          RReadHeader           : (none)
  598.                tell  UMS  that you want to read all header-field.  Useful
  599.        in combination with RTextFields only.
  600.  
  601.          RReadAll              : (none)
  602.                tell  UMS  that  you  want  to read the message-text, too.
  603.        Useful in combination with RTextFields only.
  604.  
  605.  
  606.        The following tag was not implemented in ums.library until V9.70 !
  607.  
  608.          RIDStyle              : LONG
  609.                choose  the  style  of  local  message IDs.  There are two
  610.        possible  formats of 'local' message IDs (= the IDs created by the
  611.        local system):
  612.  
  613.                a)  a  simple  decimal  number that is unique on the local
  614.        system
  615.                b)  this  decimal  number  followed by "@" and the domain-
  616.        address of the local system.  This conforms with RFC822/1036.
  617.  
  618.                Old  (obsolete) Version of ums.library (< V9.70) still use
  619.        format a), but since V9.70 versions use format b) in order to make
  620.        things cleaner and make life easier for exporters.  With format a)
  621.        exporters  must  append the domain-address to IDs themselves, with
  622.        format b) they needn't care about whether an ID is local or not.
  623.  
  624.                As  an  interim  solution  this  tag allows to specify the
  625.        desired  format.  Its  data set to 1 forces format a), 0 (default)
  626.        forces format b).
  627.  
  628.          RNoUpdate        : LONG
  629.                when  reading  its  message-text,  a  message  is  usually
  630.        updated  by having its 'Old'-flag set in your user-status.  If you
  631.        don't  want  the Old-flag to be set, use this tag and set its data
  632.        to 1.
  633.  
  634.    RESULT
  635.        success  - whether your attempt to read the message was successful
  636.                   or not.
  637.  
  638.    NOTES
  639.          The  message  will  be  buffered,  so you can easily use all the
  640.        returned  STRPTRs.   You  have  to  use  FreeUMSMsg()  to free the
  641.        buffers allocated for a certain message.
  642.  
  643.          An  user or exporter usually wants to read a single message only
  644.        once.
  645.          To  make  this  easy, ReadUMSMsg() checks whether the user reads
  646.        the 'MsgText' of a message, and, if so, sets the 'Old'-Flag in the
  647.        users status if it wasn't already set.
  648.          So  the  user (or exporte) only needs to ask for this flag to be
  649.        unset  when  using  'UMSSearch()'  before  'ReadUMSMsg()' and will
  650.        automatically avoid reading the same message a second time.
  651.  
  652.    SEE ALSO
  653.        FreeUMSMsg(), UMSSearch()
  654.  
  655. ums.library/UMSErrNum                                   ums.library/UMSErrNum
  656.  
  657.    NAME
  658.        UMSErrNum -- Return the number of the last error.
  659.  
  660.    SYNOPSIS
  661.        error = UMSErrNum( login )
  662.         D0                 D2
  663.  
  664.        WORD UMSErrNum( LONG );
  665.  
  666.    FUNCTION
  667.          UMS  functions usually  return  zero to indicate an error.  When
  668.        this  happens,  this  routine may be called to get a more specific
  669.        error code.
  670.          By  some  means,  this  routine  corresponds  to an UMS login as
  671.        dos.library/IoErr() does to a DOS-process.
  672.  
  673.    INPUTS
  674.        login - Login handle as returned by UMSLogin() or UMSRLogin().
  675.  
  676.    RESULT
  677.        error - an error number
  678.  
  679.          Possible UMS error numbers can be grouped into 4 ranges:
  680.  
  681.        0:
  682.          no error at all, the last UMS function call was successful.
  683.  
  684.        100-199:
  685.          a  slight  error.   The  last functions call was not successful,
  686.        but  may  succeed  if  some  slight  changes  will  be made to its
  687.        parameters.   E.g.   when an importer tries to import a message it
  688.        migth get error '103' when the to-user does not exist on the local
  689.        system.   It then should  change  some  message-fields in order to
  690.        forward the message to the sysop.
  691.  
  692.        200-299:
  693.          a real error.  The last function call was not successful  at all
  694.        and should not be retried.
  695.  
  696.        300-:
  697.          a  severe  error  concerning the whole system.  E.g.  the server
  698.        has  terminated.   A  program receiving such an error is recommend
  699.        to UMSLogout() and terminate asap.
  700.  
  701.    SEE ALSO
  702.        UMSErrTxt()
  703.  
  704. ums.library/UMSErrTxt                                   ums.library/UMSErrTxt
  705.  
  706.    NAME
  707.        UMSErrTxt -- Return a string describing the last error.
  708.  
  709.    SYNOPSIS
  710.        text = UMSErrTxt( login )
  711.         D0                D2
  712.  
  713.        STRPTR UMSErrTxt( LONG );
  714.  
  715.    FUNCTION
  716.          When an UMS functions fails and/or UMSErrNum() returns a nonzero
  717.        value,  you  should  use  this  routine  to  get  a  brief English
  718.        description of the last error.
  719.          Interactive  programs  should  display  this  text  to the user.
  720.        Non-interactive programs should use this text in their logfile.
  721.  
  722.    INPUTS
  723.        login - Login handle as returned by UMSLogin() or UMSRLogin().
  724.  
  725.    RESULT
  726.        text - Pointer to a String.
  727.  
  728.    NOTES
  729.          This is similiar to dos.library/Fault(), but it doesn't copy any
  730.        string, it just returns a pointer.
  731.  
  732.          You may NEVER change the string returned by UMSErrTxt()!
  733.  
  734. ums.library/UMSLogin                                     ums.library/UMSLogin
  735.  
  736.    NAME
  737.        UMSLogin -- Open the UMS MB for a certain user.
  738.  
  739.    SYNOPSIS
  740.        login = UMSLogin( user, passwd )
  741.          D0               D2     D3
  742.  
  743.        LONG UMSLogin( STRPTR, STRPTR );
  744.  
  745.    FUNCTION
  746.          Opens  the  MB,  checking  the  password and returning a 'login'
  747.        handle  when  successful.   The given 'user'-name must be known to
  748.        the MBP and the password 'passwd' must match.  If the MBP does not
  749.        already run, it will be automatically started.
  750.          All  other  functions  in  ums.library  requiry  a valid 'login'
  751.        handle to work.
  752.  
  753.    INPUTS
  754.        user   - Name or 'alias' of an user known to the MBP.
  755.        passwd - The user's correct password. A pointer to the null-string
  756.                 is allowed, NULL itself isn't.
  757.  
  758.    RESULT
  759.        login  - Internally used handle to track and remember resources
  760.                 associated  with each  Login.   Different  for a single
  761.                 user's  multiple  Logins.  One Login may be used only by
  762.                 one process at a time.
  763.  
  764.    EXAMPLE
  765.        long login = UMSLogin( "Martin Horneffer", "secret");
  766.  
  767.    NOTES
  768.          If  multiple  MBPs  are running on the same machine, you may use
  769.        UMSRLogin() to specify which one to use.
  770.  
  771.    SEE ALSO
  772.        UMSRLogin(), UMSLogout()
  773.  
  774. ums.library/UMSLogout                                   ums.library/UMSLogout
  775.  
  776.    NAME
  777.        UMSLogout -- Close a Login and free its resources.
  778.  
  779.    SYNOPSIS
  780.        UMSLogout( login )
  781.                    D2
  782.  
  783.        VOID UMSLogout( LONG );
  784.  
  785.    FUNCTION
  786.          Close  a  Login obtained with UMSLogin() or UMSRLogin() and free
  787.        all related resources.
  788.  
  789.    INPUTS
  790.        login - Login handle as returned by UMSLogin() or UMSRLogin().
  791.  
  792.    BUGS
  793.          Used to need much stack under some circumstances, thus crashing some
  794.        programs.  This should be fixed now (V9.66).
  795.  
  796.    SEE ALSO
  797.        UMSLogin(), UMSRLogin()
  798.  
  799. ums.library/UMSRLogin                                   ums.library/UMSRLogin
  800.  
  801.    NAME
  802.        UMSRLogin -- Open a certain UMS MB for a certain user.
  803.  
  804.    SYNOPSIS
  805.        login = UMSRLogin( server, user, passwd )
  806.          D0                 D2     D3     D4
  807.  
  808.        LONG UMSRLogin( STRPTR, STRPTR, STRPTR );
  809.  
  810.    FUNCTION
  811.          Like  UMSLogin(),  but  specifies  a  special  MB.  This permits
  812.        having multiple MBPs running on the same machine.  It will also be
  813.        used for specifying a MBP on a local network.
  814.  
  815.    INPUTS
  816.        server - Name of the MB.
  817.        user   - Name or 'alias' of an user know to the MBP.
  818.        passwd - The user's correct password. A pointer to the null-string
  819.                 is allowed, NULL itself isn't.
  820.  
  821.    RESULT
  822.        login  - Internally used handle to track and remember resources
  823.                 associated  with  each  Login.   Different  for a single
  824.                 user's  multiple  Logins.  One Login may be used only by
  825.                 one process at a time.
  826.  
  827.    EXAMPLE
  828.        long login = UMSRLogin( "test-server", "Martin Horneffer", "secret");
  829.  
  830.    NOTES
  831.          UMSRLogin(  "",  x, y) and UMSRLogin( NULL, x, y) both are equal
  832.        to UMSLogin( x, y).
  833.  
  834.    SEE ALSO
  835.        UMSLogin(), UMSLogout()
  836.  
  837. ums.library/UMSSearch                                   ums.library/UMSSearch
  838.  
  839.    NAME
  840.        UMSSearch -- Search a message from the MB.
  841.  
  842.    SYNOPSIS
  843.        msgNum = UMSSearch( login, tags )
  844.          D0                 D2     D3
  845.  
  846.        LONG UMSSearch( LONG, struct TagItem * );
  847.  
  848.        msgNum = UMSSearchTags( login, tag1, ... )
  849.  
  850.        LONG UMSSearchTags( LONG, ULONG, ... );
  851.  
  852.    FUNCTION
  853.          Search  the  first  (or  next)  message in the MB that fullfills
  854.        certain criteria.
  855.  
  856.          When  you  want  to  read  certain  messages  from the MB, it is
  857.        recommended that you first select these  messages with UMSSelect()
  858.        and  then  alternately  use  UMSSearch()  and ReadUMS() to get all
  859.        these messages.
  860.  
  861.    INPUTS
  862.          Allowed tags:
  863.  
  864.          SearchLast            : LONG
  865.                specify  the  last message NOT to search.  This tag allows
  866.        you  to  cycle  trough all messages fullfilling the same criteria:
  867.        set this to zero and invoke UMSSearch() the first time.  Check the
  868.        result  and  if  it's  not  zero,  put  it  in this tag and invoke
  869.        UMSSearch() again.  Repeat this until it returns zero.
  870.  
  871.          SearchDirection       : LONG
  872.                set  the  search  direction.   1  means search forward (to
  873.        higher  numbers), -1 means search backwards (to lower numbers) and
  874.        0  lets  the  MBP  decide  what  sequence to use.  This needn't be
  875.        exactly  forwards  or  backwards.   It  might  be  in a completely
  876.        different order.
  877.                When you don't depend on a certain search-direction, use 0
  878.        or omit this tag.
  879.  
  880.  
  881.          The following search operations are mutually exclusive:
  882.  
  883.        1) search for a matching status
  884.  
  885.          SearchGlobal          : (none)
  886.          SearchLocal           : (none)
  887.          SearchUser            : STRPTR
  888.          SearchMask            : LONGBITS
  889.          SearchMatch           : LONGBITS
  890.                like SelReadGlobal, SelReadLocal, SelReadUser, SelMask and
  891.        SelMatch with UMSSelect().
  892.  
  893.        2) search for a matching text
  894.  
  895.          WMsgText, ..
  896.          WMsgText + 127        : STRPTR
  897.                As for UMSSelect().
  898.  
  899.          SearchQuick           : (none)
  900.                Enable 'quick-search'.
  901.  
  902.    RESULT
  903.        msgNum - numer of a/the searched message; zero if not found.
  904.  
  905.    NOTES
  906.          Although  LONGBITS  are  used  in  the  definition,  the current
  907.        implementation only uses/supports the lower 16 bits.
  908.  
  909.    SEE ALSO
  910.        UMSSelect(), ReadUMS(), <ums.h>
  911.  
  912. ums.library/UMSSelect                                   ums.library/UMSSelect
  913.  
  914.    NAME
  915.        UMSSelect -- Select messages.
  916.  
  917.    SYNOPSIS
  918.        count = UMSSelect( login, tags )
  919.         D0                 D2     D3
  920.  
  921.        LONG UMSSelect( LONG, struct TagItem * );
  922.  
  923.        count = UMSSelectTags( login, tag1, ... )
  924.  
  925.        LONG UMSSelectTags( LONG, ULONG, ... );
  926.  
  927.    FUNCTION
  928.          Select  messages  in  the  MB according to various criteria.  To
  929.        'select'  here means to set or unset some flags, which then can be
  930.        used by UMSSearch(), stored or transferred to another user.
  931.  
  932.          UMSSelect()  can  only  do  one operation upon every invocation.
  933.        An  operation  usually  looks  for  all messages that fullfill the
  934.        specified criteria and then selects them in a specified way.
  935.  
  936.          When  you  want  to  select  messages  by  different,  logically
  937.        combined criteria, you may need to call UMSSelect() more than once
  938.        and  use  some  temporary  flags.  However, very few calls to this
  939.        functions usually should suffice.
  940.  
  941.    INPUTS
  942.  
  943.          The  following  tags  control  the selection of messages.  Thus,
  944.        they somehow specify the 'output' of the select operation.
  945.  
  946.          SelWriteGlobal        : (none)
  947.                manipulate global flags on the selected messages.
  948.  
  949.          SelWriteLocal         : (none)
  950.                manipulate your local login-flags.
  951.  
  952.          SelWriteUser          : STRPTR
  953.                manipulate another user's user-flags. You must specify the
  954.        users name (or alias).
  955.  
  956.          SelWriteGlobal,   SelWriteLocal   and  SelWriteUser  are  mutual
  957.        exclusive  --  you can  manipulate  only one flag-table at a time.
  958.        When  specifying  none  of  these  tags,  your  user-flags will be
  959.        manipulated as default.
  960.  
  961.          SelSet,
  962.          SelUnset              : LONGBITS
  963.                on  each selected message the 'SelUnset' flags are cleared
  964.        and then the 'SelSet' flags are set.
  965.        ['status = (status & ~unset) | set;']
  966.                When writing global- or user-flags, you are not allowed to
  967.        manipulate all possible flags.  See <ums.h> for protected flags.
  968.  
  969.  
  970.          The  following  tags control what and how messages are selected,
  971.        the 'input' and 'modes' of the select operation.
  972.  
  973.          SelStart,
  974.          SelStop               : LONG
  975.                Limit  the  number  of messages to be processed.  Only the
  976.        messages between these two numbers will be inspected.
  977.        ( 0 <= start < stop )!
  978.  
  979.          The following operations are mutually exclusive:
  980.  
  981.        1) select by status
  982.  
  983.          SelReadGlobal         : (none)
  984.          SelReadLocal          : (none)
  985.          SelReadUser           : STRPTR
  986.                like   SelWriteGlobal,  SelWriteLocal,  SelWriteUser,  but
  987.        specifys  which  flags to look at.  Again, your user-flags are the
  988.        default.
  989.  
  990.          SelMask,
  991.          SelMatch              : LONGBITS
  992.                specify  a  mask and a match.  If (status & mask) == match
  993.        [status * mask = match], the message will be selected.
  994.  
  995.          SelParent             : (node)
  996.               with   this   tag   specified,   each   message's  'parent'
  997.        (reference;  ->  reply-chaining)  will be inspected instead of its
  998.        own status.
  999.  
  1000.        2) select by date
  1001.  
  1002.          SelDate               : LONG
  1003.                the  messages'  dates  are compared with the supplied date
  1004.        (in  seconds  since  1.1.1978)  and  only the younger ones will be
  1005.        selected.
  1006.  
  1007.        3) select a tree
  1008.  
  1009.          SelTree               : LONG
  1010.                you  must specify  the number of a message here.  Then all
  1011.        messages being in the same reply-tree will be selected.
  1012.  
  1013.          SelSubTree            : LONG
  1014.                like  SelTree,  but  only  the  subtree  (the one with the
  1015.        specified message as its root) is selected.
  1016.  
  1017.        4) select a single message
  1018.  
  1019.          SelMsg                : LONG
  1020.                select only the specified message.
  1021.  
  1022.        5) select by text
  1023.  
  1024.          WMsgText, ..
  1025.          WMsgText + 127        : STRPTR
  1026.                when  you  specify one of these tags, the function selects
  1027.        all  messages  which  have  the  supplied  string in the specified
  1028.        field.  The strings are compared case-INsensitive.
  1029.  
  1030.          SelQuick              : (none)
  1031.                when  this tag is specified, 'quick-search' is enabled for
  1032.        selecting  texts.  This means that only some CRCs on the texts are
  1033.        compared.   This  makes  it  possible  to  select  also some wrong
  1034.        messages.   Yet,  due to the usage of 32-bit CRCs, the probability
  1035.        of  selecting  wrong  messages  is  VERY low, you most likely will
  1036.        never experience this case.
  1037.                As  'quick-search'  does  not usually need to access mass-
  1038.        storage, it is VERY FAST.
  1039.  
  1040.    RESULT
  1041.        count - how many messages have been selected.  Zero, when no
  1042.                message has been selected or an error has occured.
  1043.  
  1044.    EXAMPLE
  1045.          See SelectMail.c for examples on how to use this function.
  1046.  
  1047.    NOTES
  1048.          Although  LONGBITS  are  used  in  the  definition,  the current
  1049.        implementation only uses/supports the lower 16 bits.
  1050.  
  1051.    SEE ALSO
  1052.        UMSSearch(), <usm.h>, </demo/SelectMail.c>
  1053.  
  1054. ums.library/WriteUMSConfig                         ums.library/WriteUMSConfig
  1055.  
  1056.    NAME
  1057.        WriteUMSConfig -- Write an element to the global configuration.
  1058.  
  1059.    SYNOPSIS
  1060.        success = WriteUMSConfig( login, tags )
  1061.          D0                       D2     D3
  1062.  
  1063.        BOOL WriteUMSConfig( LONG, struct TagIten * );
  1064.  
  1065.        success = WriteUMSConfigTags( login, tag1, ... )
  1066.  
  1067.        BOOL WriteUMSConfigTags( LONG, ULONG, ... );
  1068.  
  1069.    FUNCTION
  1070.          Write or change something in the global UMS configuration.
  1071.  
  1072.    INPUTS
  1073.          Allowed tags:
  1074.  
  1075.          CfgStringData         : STRPTR
  1076.                (Not yet implemented in V9)
  1077.                this tag holds the data to be written to a string.
  1078.  
  1079.          CfgUser               : STRPTR
  1080.                (Not yet implemented in V9)
  1081.                name of the user whose config should be changed.
  1082.  
  1083.          CfgGlobalOnly         : (none)
  1084.                (Not yet implemented in V9)
  1085.                change only global config elements.
  1086.  
  1087.  
  1088.          The  following  tags are mutually exclusive.  Use exactly one of
  1089.        them.
  1090.  
  1091.          CfgStringName         : STRPTR
  1092.                (Not yet implemented in V9)
  1093.                Name of the string that should be changed.  If it does not
  1094.        already   exist,   the   string   will  be  created.   If  no  tag
  1095.        CfgStringData is specified, then the string will be deleted.
  1096.  
  1097.          CfgDump               : STRPTR
  1098.                write the current settings to a file with given name.
  1099.  
  1100.    RESULT
  1101.        success - whether it was possible and allowed to make the desired
  1102.                  write or change.
  1103.  
  1104.    BUGS
  1105.          This  function  should  provide  tags to create or delete users,
  1106.        netgroups,  akas,  etc.  These and some of the documented tags are
  1107.        not  implemented yet.  Tell the author (Martin Horneffer) when you
  1108.        need them!
  1109.  
  1110.    SEE ALSO
  1111.        ReadUMSConfig()
  1112.  
  1113. ums.library/WriteUMSMsg                               ums.library/WriteUMSMsg
  1114.  
  1115.    NAME
  1116.        WriteUMSMsg -- Write a universal message to the UMS-MB.
  1117.  
  1118.    SYNOPSIS
  1119.        msgNum = WriteUMSMsg( login, tags )
  1120.          D0                   D3     D3
  1121.  
  1122.        LONG WriteUMSMsg( LONG, struct TagItem * );
  1123.  
  1124.        msgNum = WriteUMSMsgTags( login, tag1, ... )
  1125.  
  1126.        LONG WriteUMSMsgTags( LONG, ULONG, ... );
  1127.  
  1128.    FUNCTION
  1129.          Writes  a message to the UMS message-base.  This may be either a
  1130.        new  message  to  create  or  an  already  existing  message to be
  1131.        changed.
  1132.  
  1133.          The  MBP  checks  correctness  of  the  message  and  the  users
  1134.        write-access  concerning  this message before writing it.  It also
  1135.        performs  dupe-checking,  tries to link to a tree of reply-chains,
  1136.        creates   all  desired  indices  and  computes  the  other  users'
  1137.        read-access to this message.
  1138.          All  the components of the message as well as information on how
  1139.        to do it are supplied as AmigaDOS compatible TagItems.
  1140.  
  1141.    INPUTS
  1142.          The following tags are allowed:
  1143.  
  1144.          WMsgText, ..
  1145.          WMsgText + 127        : STRPTR
  1146.                specify a certain text-field.
  1147.                A  text fields is always one null-terminated string.  Read
  1148.        the  separate documantation to see what fields and what formats of
  1149.        these fields are allowed.
  1150.                A  certain  text-field  (identified  by  its tag) may only
  1151.        appear  once in a message.  If a field is specified more than once
  1152.        in the tag list, only the latest will be used.
  1153.  
  1154.          WTextFields           : UMSMsgTextFields
  1155.                specify more than one text-field.  This points to an array
  1156.        of 128 string-pointers.  All fields you don't want to specify must
  1157.        be NULL in this array.
  1158.  
  1159.  
  1160.          WMsgNum               : LONG
  1161.                when  you want to change an old message, you must use this
  1162.        tag  to  specify  the  number of the message to change.  Don't use
  1163.        this tag when you just want to create a new message.
  1164.  
  1165.          WMsgDate              : LONG
  1166.                this  has  a very special meaning.  Specifying an AmigaDOS
  1167.        compatible  date  (seconds since 1.1.1978) with this tag indicates
  1168.        that you  want to restore an old message from a backup rather than
  1169.        writing a new one.  All users will have the 'old' flag set and not
  1170.        get this message as a new one when this tag is used.
  1171.  
  1172.        WChainUp                : LONG
  1173.                in some cases it might be unsure or impossible for the MBP
  1174.        to  build  the correct reply-chain for a message.  Use this tag to
  1175.        specify  the  number of the old message that is referred to by the
  1176.        new one.
  1177.  
  1178.        WHardLink,
  1179.        WSoftLink               : LONG
  1180.                Writing a message with a Message-ID that already exists in
  1181.        the  MB  usually  will  lead to the detection of a 'dupe'.  Yet in
  1182.        some cases it is necessary for UMS to allow multiple messages with
  1183.        the  same  Message-ID.
  1184.                This  is  made possible by the concept of message-'links'.
  1185.        With  this  concept, multiple messages sharing the same Message-ID
  1186.        (and  perhaps some more fields) are organized in a circular linked
  1187.        list.   To  create  such  a  linked list, you just write its first
  1188.        message  as  usual  and  remember  its number.  Then you write the
  1189.        other  messages  using one of the above tags to specify the number
  1190.        of the original message (or any of the already linked messages).
  1191.                The  MBP  may  optimize storage space for message links by
  1192.        only  storing  the  fields  that differ between the fields and the
  1193.        original  message.   Nevertheless  you  always have to specify the
  1194.        whole message to write a link and you will always get the complete
  1195.        message when reading a link.
  1196.                All  links to a message must consist of the same fields as
  1197.        the original message, but the contents of the fields may differ.
  1198.  
  1199.                There  are  two  sorts  of  message-links,  hardlinks  and
  1200.        softlinks.   Softlinks  describe messages that have some fields in
  1201.        common  (at  least  the  Message-ID),  but  are  really treated as
  1202.        individual  messages.   E.g.   different parts of a splitted large
  1203.        message.  Hardlinks, on the other hand, are treated as one message
  1204.        wherever  possible.  I.e.  if you read one hardlinked message, all
  1205.        the  other  links  will be marked as old, too.  RFC crosspostings,
  1206.        for instance, should be made hardlinks.
  1207.  
  1208.        WAutoBounce             : LONG
  1209.                If the msg to be written is addressed to a local user that
  1210.        doesn't  exist or to an address that no exporter can export, there
  1211.        are two possible behaviours possible for the MBP:
  1212.                a) reject the message using error-no "NoReader", expecting
  1213.        the client to care about the undeliverable message
  1214.                b)  keep  the message, forwarding it to the local sysop or
  1215.        some kind of 'bounce-daemon', so that the writing client needs not
  1216.        to care about the message any more.
  1217.                This  tag allowes to specify the desired behaviour, data=0
  1218.        forces  a),  data=1  forces b).  If this tag is not specified, the
  1219.        MBP  will  choose  the  behaviour as it wishes, maybe depending on
  1220.        whether the writing user is an exporter or not.
  1221.  
  1222.        WHdrFill,
  1223.        WTxtFill                : LONG
  1224.                specify how many bytes to reserve for later changes in the
  1225.        header/text of the message.
  1226.                The  MBP  may not be able to change an existing message if
  1227.        the   change   would   increase  the  overall  size  (maybe  after
  1228.        compression) of the message.  Since such changes are neccessary in
  1229.        some special cases, the MBP can be told to reserve some space when
  1230.        writing a message the first time.
  1231.  
  1232.                Reserving  more  than  actually needed is not a good idea,
  1233.        since  it decreases performance and wastes space.  The writer of a
  1234.        message  usually  should  know  whether  or not he will change the
  1235.        message  later on  and to what extend he will increase the size of
  1236.        the message.
  1237.  
  1238.          WNoUpdate        : LONG
  1239.            when writing a message, the 'Old'-flag in your user-status
  1240.        for  the new message will usually be set.  If you don't want this,
  1241.        use this tag and set its data to 1.
  1242.  
  1243.    RESULT
  1244.        msgNum - Number of the written message or NULL on failure.
  1245.  
  1246.    SEE ALSO
  1247.        utility/tagitem.h
  1248.  
  1249.